واجهة برمجة تطبيقات Temporal لـ JavaScript: معالجة التاريخ والوقت الحديثة

لطالما كان كائن Date في JavaScript مصدر إحباط للمطورين. أدت قابليته للتغيير، وعدم وجود دعم مدمج للمنطقة الزمنية، وواجهة برمجة التطبيقات المحرجة إلى مكتبات وحلول بديلة لا حصر لها. لحسن الحظ، تهدف واجهة برمجة تطبيقات Temporal إلى معالجة هذه العيوب، مما يوفر حلاً حديثًا وبديهيًا وواعيًا للمنطقة الزمنية لمعالجة التاريخ والوقت في JavaScript.

ما هي واجهة برمجة تطبيقات Temporal؟

واجهة برمجة تطبيقات Temporal هي كائن عام جديد، Temporal، يوفر طريقة حديثة وقياسية للعمل مع التواريخ والأوقات في JavaScript. وهي مصممة لتحل محل كائن Date القديم، وتقدم تحسينات كبيرة من حيث تصميم واجهة برمجة التطبيقات، وعدم القابلية للتغيير، ودعم المنطقة الزمنية، وسهولة الاستخدام بشكل عام. وهي جزء من اقتراح ECMAScript ويجري تنفيذها في محركات JavaScript الرئيسية.

الفوائد الرئيسية لواجهة برمجة تطبيقات Temporal:

• عدم القابلية للتغيير: كائنات Temporal غير قابلة للتغيير، مما يعني أن العمليات عليها تُرجع كائنات جديدة بدلاً من تعديل الأصل. يساعد هذا في منع الآثار الجانبية غير المتوقعة ويجعل من السهل التفكير في التعليمات البرمجية.
• واجهة برمجة تطبيقات واضحة: تم تصميم واجهة برمجة التطبيقات لتكون أكثر سهولة واتساقًا من كائن Date القديم.
• دعم المنطقة الزمنية: توفر Temporal دعمًا قويًا للمناطق الزمنية، مما يسمح لك بالعمل مع التواريخ والأوقات في مواقع مختلفة حول العالم.
• دعم التقويم: إلى جانب التقويم الغريغوري، تسمح واجهة برمجة التطبيقات باستخدام أنظمة تقويم أخرى، مما يسهل التطبيقات العالمية.
• التعامل مع الثواني الكبيسة: تأخذ واجهة برمجة تطبيقات Temporal في الاعتبار الثواني الكبيسة، مما يوفر حسابات وقت أكثر دقة.

البدء باستخدام Temporal

في حين أن واجهة برمجة تطبيقات Temporal لا تزال قيد التطوير وليست مدعومة بالكامل في جميع المتصفحات وبيئات Node.js، يمكنك استخدام polyfill للبدء في تجربتها اليوم. يمكنك تثبيت polyfill عبر npm:

            npm install @js-temporal/polyfill
            

              
                Copy
              
            
          

ثم، استورد polyfill في كود JavaScript الخاص بك:

            import { Temporal } from '@js-temporal/polyfill';
            

              
                Copy
              
            
          

بمجرد تثبيت polyfill، يمكنك البدء في استخدام كائن Temporal وفئاته المختلفة.

فئات Temporal الأساسية

توفر واجهة برمجة تطبيقات Temporal العديد من الفئات الرئيسية للعمل مع التواريخ والأوقات:

• Temporal.PlainDate: يمثل تاريخ التقويم (السنة والشهر واليوم) بدون أي معلومات عن المنطقة الزمنية أو الوقت من اليوم.
• Temporal.PlainTime: يمثل وقتًا من اليوم (الساعة والدقيقة والثانية وجزء من الثانية) بدون أي معلومات عن التاريخ أو المنطقة الزمنية.
• Temporal.PlainDateTime: يمثل التاريخ والوقت بدون أي معلومات عن المنطقة الزمنية.
• Temporal.ZonedDateTime: يمثل التاريخ والوقت مع منطقة زمنية محددة.
• Temporal.Instant: يمثل نقطة زمنية محددة، مقاسة بالنانوثانية منذ الحقبة الزمنية لـ Unix (1 يناير 1970، الساعة 00:00:00 التوقيت العالمي المنسق (UTC)).
• Temporal.TimeZone: يمثل منطقة زمنية.
• Temporal.Duration: يمثل مدة زمنية، مثل الساعات أو الدقائق أو الثواني.
• Temporal.Now: يوفر الوصول إلى التاريخ والوقت الحاليين.

العمل مع PlainDate

تمثل الفئة Temporal.PlainDate تاريخًا بدون أي معلومات عن المنطقة الزمنية أو الوقت من اليوم. وهي مفيدة لتمثيل أعياد الميلاد أو الذكرى السنوية أو الأحداث الأخرى القائمة على التاريخ.

إنشاء PlainDate:

            const plainDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26 });
console.log(plainDate.toString()); // Output: 2024-10-26
            

              
                Copy
              
            
          

يمكنك أيضًا إنشاء PlainDate من سلسلة بتنسيق ISO 8601:

            const plainDateFromString = Temporal.PlainDate.from('2024-12-25');
console.log(plainDateFromString.toString()); // Output: 2024-12-25
            

              
                Copy
              
            
          

الوصول إلى مكونات التاريخ:

            const year = plainDate.year; // 2024
const month = plainDate.month; // 10
const day = plainDate.day;   // 26
const dayOfWeek = plainDate.dayOfWeek; // Day of the week (1-7, Monday-Sunday)
const dayOfYear = plainDate.dayOfYear; // Day of the year (1-366)
const daysInMonth = plainDate.daysInMonth; // Number of days in the month
const isLeapYear = plainDate.isLeapYear;   // Boolean indicating if the year is a leap year
            

              
                Copy
              
            
          

إضافة وطرح الأيام:

            const nextDay = plainDate.add({ days: 1 });
console.log(nextDay.toString()); // Output: 2024-10-27

const previousWeek = plainDate.subtract({ weeks: 1 });
console.log(previousWeek.toString()); // Output: 2024-10-19
            

              
                Copy
              
            
          

مقارنة التواريخ:

            const anotherDate = Temporal.PlainDate.from({ year: 2024, month: 11, day: 15 });

if (plainDate.equals(anotherDate)) {
  console.log('Dates are equal');
} else if (plainDate.lessThan(anotherDate)) {
  console.log('plainDate is earlier than anotherDate');
} else {
  console.log('plainDate is later than anotherDate');
}
// Output: plainDate is earlier than anotherDate
            

              
                Copy
              
            
          

العمل مع PlainTime

تمثل الفئة Temporal.PlainTime وقتًا من اليوم بدون أي معلومات عن التاريخ أو المنطقة الزمنية. وهي مفيدة لتمثيل ساعات العمل أو أوقات الاجتماعات أو الأحداث الأخرى القائمة على الوقت.

إنشاء PlainTime:

            const plainTime = Temporal.PlainTime.from({ hour: 14, minute: 30, second: 0 });
console.log(plainTime.toString()); // Output: 14:30:00
            

              
                Copy
              
            
          

يمكنك أيضًا إنشاء PlainTime من سلسلة بتنسيق ISO 8601:

            const plainTimeFromString = Temporal.PlainTime.from('09:00:00');
console.log(plainTimeFromString.toString()); // Output: 09:00:00
            

              
                Copy
              
            
          

الوصول إلى مكونات الوقت:

            const hour = plainTime.hour;   // 14
const minute = plainTime.minute; // 30
const second = plainTime.second; // 0
const millisecond = plainTime.millisecond; // 0
const microsecond = plainTime.microsecond; // 0
const nanosecond = plainTime.nanosecond;   // 0
            

              
                Copy
              
            
          

إضافة وطرح الوقت:

            const laterTime = plainTime.add({ minutes: 15 });
console.log(laterTime.toString()); // Output: 14:45:00

const earlierTime = plainTime.subtract({ hours: 1 });
console.log(earlierTime.toString()); // Output: 13:30:00
            

              
                Copy
              
            
          

مقارنة الأوقات:

            const anotherTime = Temporal.PlainTime.from({ hour: 15, minute: 0, second: 0 });

if (plainTime.equals(anotherTime)) {
  console.log('Times are equal');
} else if (plainTime.lessThan(anotherTime)) {
  console.log('plainTime is earlier than anotherTime');
} else {
  console.log('plainTime is later than anotherTime');
}
// Output: plainTime is earlier than anotherTime
            

              
                Copy
              
            
          

العمل مع PlainDateTime

تمثل الفئة Temporal.PlainDateTime التاريخ والوقت بدون أي معلومات عن المنطقة الزمنية. وهي تجمع بين وظائف PlainDate و PlainTime.

إنشاء PlainDateTime:

            const plainDateTime = Temporal.PlainDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0 });
console.log(plainDateTime.toString()); // Output: 2024-10-26T14:30:00
            

              
                Copy
              
            
          

يمكنك أيضًا إنشاء PlainDateTime من سلسلة بتنسيق ISO 8601:

            const plainDateTimeFromString = Temporal.PlainDateTime.from('2024-12-25T09:00:00');
console.log(plainDateTimeFromString.toString()); // Output: 2024-12-25T09:00:00
            

              
                Copy
              
            
          

الوصول إلى مكونات التاريخ والوقت:

            const year = plainDateTime.year;   // 2024
const month = plainDateTime.month; // 10
const day = plainDateTime.day;     // 26
const hour = plainDateTime.hour;   // 14
const minute = plainDateTime.minute; // 30
const second = plainDateTime.second; // 0
            

              
                Copy
              
            
          

إضافة وطرح التواريخ والأوقات:

            const nextDayAndTime = plainDateTime.add({ days: 1, hours: 2 });
console.log(nextDayAndTime.toString()); // Output: 2024-10-27T16:30:00

const previousWeekAndTime = plainDateTime.subtract({ weeks: 1, minutes: 30 });
console.log(previousWeekAndTime.toString()); // Output: 2024-10-19T14:00:00
            

              
                Copy
              
            
          

التحويل إلى PlainDate و PlainTime:

            const plainDateFromDateTime = plainDateTime.toPlainDate();
console.log(plainDateFromDateTime.toString()); // Output: 2024-10-26

const plainTimeFromDateTime = plainDateTime.toPlainTime();
console.log(plainTimeFromDateTime.toString()); // Output: 14:30:00
            

              
                Copy
              
            
          

العمل مع ZonedDateTime

تمثل الفئة Temporal.ZonedDateTime التاريخ والوقت مع منطقة زمنية محددة. وهذا أمر بالغ الأهمية للتطبيقات التي تحتاج إلى التعامل مع التواريخ والأوقات في مواقع مختلفة حول العالم. على عكس كائن Date القديم، يوفر Temporal دعمًا مدمجًا للمنطقة الزمنية.

إنشاء ZonedDateTime:

            const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });
console.log(zonedDateTime.toString()); // Output: 2024-10-26T14:30:00-07:00[America/Los_Angeles]
            

              
                Copy
              
            
          

يمكنك أيضًا إنشاء ZonedDateTime من Instant ومنطقة زمنية:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Example timestamp
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('Europe/London');
console.log(zonedDateTimeFromInstant.toString()); // Output will vary based on the actual instant but will reflect the date/time in Europe/London
            

              
                Copy
              
            
          

الوصول إلى مكونات التاريخ والوقت:

            const year = zonedDateTime.year;   // 2024
const month = zonedDateTime.month; // 10
const day = zonedDateTime.day;     // 26
const hour = zonedDateTime.hour;   // 14
const minute = zonedDateTime.minute; // 30
const second = zonedDateTime.second; // 0
const timeZone = zonedDateTime.timeZone; // Temporal.TimeZone object
            

              
                Copy
              
            
          

التحويل بين المناطق الزمنية:

            const newYorkDateTime = zonedDateTime.withTimeZone('America/New_York');
console.log(newYorkDateTime.toString()); // Output: 2024-10-26T17:30:00-04:00[America/New_York]
            

              
                Copy
              
            
          

التعامل مع التوقيت الصيفي (DST):

يتعامل Temporal تلقائيًا مع انتقالات DST. عند إضافة الوقت أو طرحه، فإنه يأخذ DST في الاعتبار، مما يضمن نتائج دقيقة. على سبيل المثال، ضع في اعتبارك اجتماعًا مجدولاً عبر انتقال DST في ألمانيا:

            const meetingStart = Temporal.ZonedDateTime.from({ year: 2024, month: 3, day: 31, hour: 2, minute: 30, timeZone: 'Europe/Berlin' });
const meetingEnd = meetingStart.add({ hours: 1 }); // Adding 1 hour
console.log(meetingEnd.toString()); // Output: 2024-03-31T03:30:00+02:00[Europe/Berlin]. Notice the offset changes due to DST
            

              
                Copy
              
            
          

العمل مع Instant

تمثل الفئة Temporal.Instant نقطة زمنية محددة، مقاسة بالنانوثانية منذ الحقبة الزمنية لـ Unix. وهي مفيدة لتخزين ومقارنة اللحظات الدقيقة في الوقت المناسب.

إنشاء Instant:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Example Unix timestamp in seconds
console.log(instant.toString()); // Output will be an ISO string representation of that instant
            

              
                Copy
              
            
          

التحويل إلى ZonedDateTime:

            const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('America/Los_Angeles');
console.log(zonedDateTimeFromInstant.toString()); // Output: Date and time in America/Los_Angeles corresponding to the instant
            

              
                Copy
              
            
          

مقارنة Instants:

            const anotherInstant = Temporal.Instant.fromEpochSeconds(1666790000);

if (instant.equals(anotherInstant)) {
  console.log('Instants are equal');
} else if (instant.lessThan(anotherInstant)) {
  console.log('instant is earlier than anotherInstant');
} else {
  console.log('instant is later than anotherInstant');
}
// Output: instant is earlier than anotherInstant
            

              
                Copy
              
            
          

العمل مع Duration

تمثل الفئة Temporal.Duration مدة زمنية، مثل الساعات أو الدقائق أو الثواني. وهي مفيدة لحساب الفرق بين تاريخين أو وقتين.

إنشاء Duration:

            const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
console.log(duration.toString()); // Output: PT2H30M
            

              
                Copy
              
            
          

حساب الفرق بين التواريخ/الأوقات:

            const startDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 1, hour: 0, minute: 0, second: 0 });
const endDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 3, hour: 12, minute: 30, second: 0 });
const difference = endDate.since(startDate);
console.log(difference.toString()); // Output: P2DT12H30M

// Accessing the components of the duration
console.log(difference.days);    // 2
console.log(difference.hours);   // 12
console.log(difference.minutes); // 30
            

              
                Copy
              
            
          

إضافة المدة إلى التواريخ/الأوقات:

            const newDate = startDate.add(duration);
console.log(newDate.toString()); // Output: 2024-01-03T02:30:00
            

              
                Copy
              
            
          

العمل مع التقويمات

تدعم واجهة برمجة تطبيقات Temporal أنظمة تقويم مختلفة بخلاف التقويم الغريغوري. في حين أنها غير مطبقة بالكامل في جميع polyfills والمحركات حتى الآن، فإن القصد هو السماح للتطبيقات بالتعامل مع التواريخ في التقويمات الخاصة بالثقافات المختلفة. على سبيل المثال، لاستخدام التقويم الياباني (افتراضيًا، حيث لا يزال التنفيذ يتطور):

            // This is a conceptual example as calendar support is still under development
// const japaneseDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26, calendar: 'japanese' });
// console.log(japaneseDate.toString()); // Expected: Output formatted according to the Japanese calendar

            

              
                Copy
              
            
          

ملاحظة: يعد دعم التقويم ميزة متطورة لواجهة برمجة تطبيقات Temporal، ولم تتوفر الوظائف الكاملة بعد عالميًا.

أمثلة عملية وحالات الاستخدام

توفر واجهة برمجة تطبيقات Temporal مجموعة واسعة من الاحتمالات للتعامل مع التواريخ والأوقات في JavaScript. فيما يلي بعض الأمثلة العملية وحالات الاستخدام:

• جدولة المواعيد: قم بإنشاء تطبيق جدولة يسمح للمستخدمين بحجز المواعيد في منطقتهم الزمنية المحلية. يجعل Temporal.ZonedDateTime من السهل التحويل بين المناطق الزمنية والتعامل مع انتقالات DST. بالنسبة لعيادة في برلين تقوم بجدولة المواعيد عالميًا:

            const appointmentTimeBerlin = Temporal.ZonedDateTime.from({ year: 2024, month: 11, day: 5, hour: 10, minute: 0, timeZone: 'Europe/Berlin' });
const appointmentTimeLA = appointmentTimeBerlin.withTimeZone('America/Los_Angeles');
console.log(`Appointment Time in Berlin: ${appointmentTimeBerlin.toString()}`);
console.log(`Appointment Time in Los Angeles: ${appointmentTimeLA.toString()}`);
            

              
                Copy
              
            
          

• حساب العمر: تحديد عمر المستخدم بناءً على تاريخ ميلاده. يتيح لك PlainDate تمثيل تاريخ الميلاد بدون أي معلومات عن المنطقة الزمنية.

            const birthDate = Temporal.PlainDate.from({ year: 1990, month: 5, day: 15 });
const today = Temporal.Now.plainDateISO();
const age = today.year - birthDate.year - (today.month < birthDate.month || (today.month === birthDate.month && today.day < birthDate.day) ? 1 : 0);
console.log(`Age: ${age}`);
            

              
                Copy
              
            
          

• عرض التواريخ والأوقات بتنسيقات مختلفة: تنسيق التواريخ والأوقات وفقًا للإعدادات المحلية للمستخدم. في حين أن ميزات التدويل (Intl) منفصلة، يمكن تنسيق كائنات Temporal بسهولة باستخدام toLocaleString() أو طرق مماثلة عند دمجها مع ميزات واجهة برمجة تطبيقات Intl.

            const zonedDateTimeNow = Temporal.Now.zonedDateTimeISO('en-GB');
console.log(zonedDateTimeNow.toLocaleString('en-GB'));
console.log(zonedDateTimeNow.toLocaleString('de-DE'));
            

              
                Copy
              
            
          

• تتبع مدة الأحداث: حساب مدة الحدث وعرضه بتنسيق مقروء. تتيح لك المدة تمثيل الفرق الزمني بين تاريخين أو وقتين.

            const eventStart = Temporal.Instant.fromEpochSeconds(1700000000); // Example start timestamp
const eventEnd = Temporal.Instant.fromEpochSeconds(1700005000);   // Example end timestamp
const durationOfEvent = eventEnd.since(eventStart);
console.log(`Event duration: ${durationOfEvent.minutes} minutes`);
            

              
                Copy
              
            
          

أفضل الممارسات لاستخدام واجهة برمجة تطبيقات Temporal

فيما يلي بعض أفضل الممارسات التي يجب وضعها في الاعتبار عند استخدام واجهة برمجة تطبيقات Temporal:

• استخدم عدم القابلية للتغيير: احتضن عدم القابلية للتغيير لكائنات Temporal. تجنب تعديل الكائنات مباشرة. بدلاً من ذلك، قم بإنشاء كائنات جديدة باستخدام طرق مثل add و subtract و with.
• التعامل مع المناطق الزمنية بعناية: كن على دراية بالمناطق الزمنية عند العمل مع التواريخ والأوقات. استخدم ZonedDateTime عندما تحتاج إلى تمثيل التواريخ والأوقات في منطقة زمنية معينة.
• استخدم أسماء متغيرات واضحة: استخدم أسماء متغيرات وصفية تشير بوضوح إلى نوع كائن Temporal المستخدم (على سبيل المثال، plainDate، zonedDateTime، duration).
• ضع في اعتبارك Polyfills: نظرًا لأن Temporal لا يزال جديدًا نسبيًا، تأكد من الدعم الكافي باستخدام مكتبة polyfill عند الحاجة.
• التحقق من صحة الإدخال: تحقق دائمًا من صحة إدخال المستخدم للتأكد من أن التواريخ والأوقات بالتنسيق الصحيح.

ترحيل من Date القديم

يمكن أن يكون الترحيل من كائن Date القديم عملية تدريجية. ضع في اعتبارك هذه الاستراتيجيات:

• الاعتماد التدريجي: ابدأ باستخدام Temporal في التعليمات البرمجية الجديدة مع الحفاظ على Date في الأجزاء الموجودة من تطبيقك.
• دوال التغليف: قم بإنشاء دوال تغليف تحول بين كائنات Date و Temporal لتسهيل التشغيل البيني أثناء الترحيل.
• الاختبار الشامل: اختبر الترحيل على نطاق واسع للتأكد من أن جميع حسابات التاريخ والوقت دقيقة.

واجهة برمجة تطبيقات Temporal مقابل Moment.js

كان Moment.js مكتبة شائعة لمعالجة التاريخ والوقت في JavaScript، ولكنها تعتبر الآن مشروعًا قديمًا وهي في وضع الصيانة. توفر واجهة برمجة تطبيقات Temporal حلاً أكثر حداثة ومعياريًا يعالج العديد من أوجه القصور في Moment.js. Moment.js قابل للتغيير ويفتقر إلى دعم المنطقة الزمنية الأصلية. واجهة برمجة تطبيقات Temporal غير قابلة للتغيير ولديها دعم المنطقة الزمنية الأصلية.

الخلاصة

تمثل واجهة برمجة تطبيقات JavaScript Temporal تحسنًا كبيرًا على كائن Date القديم. إن عدم قابليته للتغيير، وواجهة برمجة التطبيقات الواضحة، ودعم المنطقة الزمنية، ودعم التقويم تجعلها أداة قوية للتعامل مع التواريخ والأوقات في تطبيقات JavaScript الحديثة. في حين أن الاعتماد لا يزال في ازدياد، فإن استخدام polyfill يسمح لك بالبدء في الاستفادة من مزاياه اليوم. عندما تصبح واجهة برمجة التطبيقات مدعومة على نطاق أوسع، فمن المتوقع أن تصبح الطريقة القياسية للعمل مع التواريخ والأوقات في JavaScript.

احتضن واجهة برمجة تطبيقات Temporal وافتح طريقة أكثر كفاءة وموثوقية لإدارة التواريخ والأوقات في مشاريعك، مما يضمن أن تطبيقك يتعامل مع المناطق الزمنية العالمية والحسابات بدقة.